Skip to content

Add documentation for RID-specific and AOT .NET tools #49874

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

Add documentation for RID-specific and AOT .NET tools #49874

wants to merge 4 commits into from
+222 −0

Conversation

Copy link
Contributor

Copilot AI commented Nov 12, 2025 •
edited by github-actions bot
Loading

Summary

Adds comprehensive documentation for RID-specific and AOT-enabled .NET tools introduced in SDK 10.0.100-preview.6, enabling platform-specific distribution of native, trimmed tools.

Fixes #503206

Changes

New Article: rid-specific-tools.md

Documents the complete workflow for creating platform-specific tools:

  • Opt-in configuration: RuntimeIdentifiers or ToolPackageRuntimeIdentifiers MSBuild properties
  • Packaging workflows:
    • Non-AOT: Single dotnet pack generates N+1 packages (one per RID + pointer)
    • AOT: Requires per-platform dotnet pack -r <RID> on target systems
  • Package types: DotnetTool (metadata) vs DotnetToolRidPackage (binaries)
  • Installation: CLI automatically selects appropriate RID package from metadata
  • Complete AOT example: End-to-end implementation with multi-platform packaging

Cross-references

  • Added links from global-tools-how-to-create.md and global-tools.md

Example Configuration

<PropertyGroup>
  <PackAsTool>true</PackAsTool>
  <ToolCommandName>mytool</ToolCommandName>
  <RuntimeIdentifiers>win-x64;linux-x64;osx-arm64</RuntimeIdentifiers>
  <PublishAot>true</PublishAot>
</PropertyGroup>

Produces packages: mytool.1.0.0.nupkg, mytool.win-x64.1.0.0.nupkg, mytool.linux-x64.1.0.0.nupkg, mytool.osx-arm64.1.0.0.nupkg

Original prompt

This section details on the original issue you should resolve

<issue_title>[New article]: dotnet tools support RID-specific and AOT packages</issue_title>
<issue_description>### Proposed topic or title

dotnet tools can be RID-specific, self-contained, or AOT applications now

Location in table of contents.

No response

Reason for the article

In .NET SDK 10.0.100-preview.6 we added support for a new way of authoring tools that enables packaging them for specific platforms and architectures. This makes it much simpler to easily distribute native, fast, trimmed .NET applications for use cases like MCP servers.

Article abstract

  • How to opt in to the new behaviors
    • set RuntimeIdentifiers or ToolPackageRuntimeIdentifiers MSBuild properties to a semicolon-delimited list of RID values (win-x64;osx-arm64, etc).
  • How the tooling reacts to the new model
    • If you're not doing AOT - dotnet pack on the tool will create N+1 NuGet packages - one for each RID called <packageName>.<RID>.<packageVersion>.nupkg, and as a RID-less pointer called <packageName>.<packageVersion>.nupkg like today.
    • If you are doing AOT, then you need to dotnet pack once for the top-level package, but then on separate platforms call dotnet pack -r <RID> to make the RID-specific packages manually
    • The top-level package has the same PackageType (DotnetTool), but the RID-specific packages have a new PackageType (DotnetToolRidPackage)
    • The top-level package contains metadata signalling that it is a RID-specific tool, and what the RID-specific packages are
    • Push all of these to NuGet.org
    • on dotnet tool install, if the top-level package's metadata signals that it is a RID-specific tool, the CLI will find and install the most relevant package for the user's current platform and invoke that
  • Sample application

There is no design for this feature.
Initial implementation at dotnet/sdk#48575, follow-up usability tweaks at dotnet/sdk#49288

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

  • ID: b7e47565-cc59-b1a6-24be-0143c550c0b2
  • Version Independent ID: c6859ca6-e2b1-3645-872c-60390ffd429a
  • Platform ID: 71f88ad0-c497-bd84-bcae-a271c6be9107
  • Content: .NET CLI
  • Content Source: docs/core/tools/index.md
  • Service: dotnet-fundamentals
  • GitHub Login: @tdykstra
  • Microsoft Alias: tdykstra

Associated WorkItem - 503206</issue_description>

Comments on the Issue (you are @copilot in this section)

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Internal previews

📄 File 🔗 Preview link
docs/core/tools/global-tools-how-to-create.md Tutorial: Create a .NET tool using the .NET CLI
docs/core/tools/global-tools.md How to manage .NET tools
docs/core/tools/rid-specific-tools.md Create RID-specific, self-contained, and AOT .NET tools
docs/navigate/tools-diagnostics/toc.yml docs/navigate/tools-diagnostics/toc

Copilot AI changed the title [WIP] Add article on dotnet tools support for RID-specific and AOT packages Add documentation for RID-specific and AOT .NET tools Nov 12, 2025
Copilot AI requested a review from meaghanlewis November 12, 2025 23:46
Copilot finished work on behalf of meaghanlewis November 12, 2025 23:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@meaghanlewis meaghanlewis Awaiting requested review from meaghanlewis meaghanlewis is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

@meaghanlewis meaghanlewis

Copilot code review Copilot

Labels

dotnet-cli/subsvc dotnet-fundamentals/svc

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[New article]: dotnet tools support RID-specific and AOT packages

2 participants

@meaghanlewis